Skip to content

feat(mcp): Add tool annotations for improved LLM tool understanding #2820

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
triepod-ai wants to merge 2 commits into
base: main
Choose a base branch
from
Open

feat(mcp): Add tool annotations for improved LLM tool understanding #2820

triepod-ai wants to merge 2 commits into from

Conversation

@triepod-ai
Copy link

@triepod-ai triepod-ai commented Dec 27, 2025 •
edited
Loading

Summary

Adds MCP tool annotations (readOnlyHint, destructiveHint) to all 15 tools to help LLMs better understand tool behavior and make safer decisions about tool execution.

This is an unsolicited contribution to improve the MCP ecosystem. No existing issue to reference.

✅ Checklist

  • I have followed every step in the contributing guide
  • The PR title follows the convention (feat(mcp): ...)
  • I ran and tested the code works

Testing

  1. Build verification: TypeScript compiles without errors

    pnpm build --filter=@trigger.dev/cli-v3

  2. Annotation format verification: Confirmed annotations follow MCP specification:

    • readOnlyHint: true for read-only tools (queries, fetches, lists)
    • destructiveHint: true for state-modifying tools (create, deploy, cancel)

  3. Live verification pending: Full MCP client integration testing requires environment setup with API credentials

Changelog

  • Added readOnlyHint: true to 10 read-only tools:

    • searchDocsTool, listOrgsTool, listProjectsTool, getCurrentWorker
    • listRunsTool, getRunDetailsTool, waitForRunToCompleteTool
    • listDeploysTool, listPreviewBranchesTool

  • Added destructiveHint: true to 5 state-modifying tools:

    • createProjectInOrgTool, initializeProjectTool, triggerTaskTool
    • cancelRunTool, deployTool

  • Updated registerTool() in tools.ts to pass annotation fields

Why This Matters

  • Annotations provide semantic metadata that helps LLMs understand tool behavior
  • LLMs can make better decisions about when to use tools and in what order
  • Enables safer tool execution by distinguishing read-only from destructive operations
  • Follows the MCP Tool Annotations specification

Screenshots

N/A - metadata-only changes with no UI impact

@web-flow @claude
feat(mcp): Add tool annotations for improved LLM tool understanding
6161130 
Add `readOnlyHint` and `destructiveHint` annotations to all 15 MCP tools
to help AI/LLM agents better understand the safety characteristics of
each tool:

Read-only tools (10):
- searchDocsTool - Search documentation
- listOrgsTool - List organizations
- listProjectsTool - List projects
- getCurrentWorker - Get current worker info
- listRunsTool - List runs
- getRunDetailsTool - Get run details
- waitForRunToCompleteTool - Wait for run completion
- listDeploysTool - List deployments
- listPreviewBranchesTool - List preview branches

Destructive tools (5):
- createProjectInOrgTool - Creates a new project
- initializeProjectTool - Initializes a project
- triggerTaskTool - Triggers task execution
- cancelRunTool - Cancels a running task
- deployTool - Deploys code to environment

These annotations follow the MCP specification and help AI agents
make informed decisions about which tools require user confirmation
before execution.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@changeset-bot
Copy link

changeset-bot bot commented Dec 27, 2025 •
edited
Loading

🦋 Changeset detected

Latest commit: daee2f4

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 26 packages
Name Type
trigger.dev Patch
d3-chat Patch
references-d3-openai-agents Patch
references-nextjs-realtime Patch
references-realtime-hooks-test Patch
references-realtime-streams Patch
references-telemetry Patch
@trigger.dev/build Patch
@trigger.dev/core Patch
@trigger.dev/python Patch
@trigger.dev/react-hooks Patch
@trigger.dev/redis-worker Patch
@trigger.dev/rsc Patch
@trigger.dev/schema-to-json Patch
@trigger.dev/sdk Patch
@trigger.dev/database Patch
@trigger.dev/otlp-importer Patch
@internal/cache Patch
@internal/clickhouse Patch
@internal/redis Patch
@internal/replication Patch
@internal/run-engine Patch
@internal/schedule-engine Patch
@internal/testcontainers Patch
@internal/tracing Patch
@internal/zod-worker Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

@coderabbitai
Copy link
Contributor

coderabbitai bot commented Dec 27, 2025 •
edited
Loading

Walkthrough

The pull request adds two new metadata fields—readOnlyHint and destructiveHint—to tool definitions across multiple files in the CLI-v3 MCP tools package. These fields are added to tools in deploys.ts, docs.ts, orgs.ts, previewBranches.ts, runs.ts, and tasks.ts, with read-only operations marked as (true, false) and state-mutating operations marked as (false, true). The base tool registration payload in tools.ts is also extended to support these annotation fields. No functional logic, control flow, or error handling is altered.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 1
❌ Failed checks (1 warning)
Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (2 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely summarizes the main change: adding tool annotations to improve LLM understanding of MCP tools.
Description check ✅ Passed The description follows the template structure with all required sections completed: checklist marked, testing steps detailed, changelog comprehensive, and rationale explained.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

📜 Recent review details

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 6161130 and daee2f4.

📒 Files selected for processing (1)
  • .changeset/add-mcp-tool-annotations.md
🔇 Additional comments (1)
.changeset/add-mcp-tool-annotations.md (1)

1-7: Verify the version bump type (patch vs. minor).

Adding new metadata fields (readOnlyHint and destructiveHint) typically constitutes a feature addition, which would warrant a "minor" version bump under semantic versioning rather than "patch". While these are metadata-only changes with no behavioral impact, they do extend the tool definition schema.

Please confirm whether "patch" aligns with this project's versioning conventions for optional metadata additions, or if "minor" would be more appropriate.

✏️ Tip: You can disable this entire section by setting review_details to false in your review settings.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@vibe-kanban-cloud
Copy link

vibe-kanban-cloud bot commented Dec 27, 2025

Review Complete

Your review story is ready!

View Story

Comment !reviewfast on this PR to re-generate the story.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@triepod-ai @web-flow